{ /* This Source Code Form is subject to the terms of the Mozilla Public
  License, v. 2.0. If a copy of the MPL was not distributed with this
  file, You can obtain one at http://mozilla.org/MPL/2.0/.

  Copyright (c) KALEIDOS INC */ }

import { Canvas, Meta } from '@storybook/addon-docs/blocks';
import * as InputStories from "./input.stories";

<Meta title="Controls/Input" />

# Input

The `input*` component is a wrapper composed of `label*`, `input-field*`, and `hint-message*` components, functioning as a form element that adapts its UI based on configuration, making it suitable for different areas of the interface.

<Canvas of={InputStories.Default} />

## Technical notes

### Icons

`input*` accepts an `icon` prop, which must contain an [icon ID](../foundations/assets/icon.mdx).
These are available in the `app.main.ds.foundations.assets.icon` namespace.

```clj
(ns app.main.ui.foo
  (:require
   [app.main.ui.ds.foundations.assets.icon :as i]))
```

```clj
[:> input* {:icon i/effects}]
```

## Destructuring the component

The `input*` component is composed of `label*`, `input-field*`, and `hint-message*` components. If you only need some of these components or require them to be broken down, you can build them as a group of components.

```clj
[:> label* {:for id :is-optional true} label]
[:> input-field* {:id id}]
[:> hint-message* {:id id :message message :type "warning}]
```

<Canvas of={InputStories.Composable} />

#### `input-field*` slots

The `input-field*` offers two slots where developers can include external components as properties.

- **slot-start**: adds a component to the beginning of the input
- **slot-end**: adds a component to the end of the input

```clj
[:> input-field* {:id id :slot-start component-one :slot-end component-two}]
```

<Canvas of={InputStories.Slots} />

## Usage guidelines (design)

### Where to use

In forms where the user needs to input any short text or number.

### When to use

When the information that is needed is short and needs an element to add context
for using it or additional functionality (like color picker).

### Size

The width of the component depends on the content and layout. They can expand to
fill the container or the content area to which they relate (e.g. tabs) and adapt
depending on whether there are one or two input elements with or without buttons
next to them. Their height is always fixed, `32px`, with text area being used for
larger text blocks.
